Atari Forever 4

home *** CD-ROM | disk | FTP | other *** search

/ Atari Forever 4 / Atari Forever 4.zip / Atari Forever 4.iso / FALCON / DEMOSRGB / FD_RGB06 / U_TRACK / DOCS / ENGLISH.TXT next >

Wrap

Text File | 1998-03-14 | 21KB | 457 lines

Ultimate Tracker 2.0 * A Retour 2048 Software * By : - Checksum of Equinox (Amiga adaptation) - Edy of Equinox (Falcon adaptation) - Sharp Man of The Black Cats (Program) _________________________________________________________________ English Documentation _________________________________________________________________ 1. Overall = ======= This program replays Amiga (or Atari) soundtracker, Noisetrac- ker or Protracker 1.2 modules. It runs on all Atari systems with a DMA soundchip (STe, Mega STe, TT or Falcon). It can be used as well as a normal program as a desk accessory. Since the version 2.0, the player uses the MFP i7 interrupt instead of the timer A. So now, all timers are free (particulary the timer used by AES in evnt_timer). 2. How does it run ? = ================= There's three ways to launch this program : As a normal program (extension is .PRG or .APP) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Just click onto the icon of the player to launch it. When the program is loaded, the player is displayed into a GEM window. There's also a GEM menu to access to the desk accessories (like the CPX sound manager). You can load a module or quit the program directly thanks to this menu. As a GEM program which needs parameters (extension is .GTP) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Click onto the icon of the player to launch it. Then, a dialog box appears and asks you to enter parameters. Parameters needed are the path and the name of a module, just type it and press return. The player will load and play the module automatically. If you type return without typing anything, the program will act in the same way of a normal GEM program. Note that you can drag the icon of a module and drop it onto the icon of the player, the player will load and play this module. (This last feature is available only with TOS version > 1.62). Thanks to this feature, you can install the player as an application for the files *.MOD in the menu "options" of the desktop. When you'll click onto a module, the player will play it automatically. As a desk accessory (extension is .ACC) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Install the player on the root of your boot disk and reboot the computer, the player will automatically loaded, then you can invoque it from any application. Moreover you can play a module everywhere in background. This feature is only available when the player is launched as a desk accessory. You can use the accessory as an application for *.MOD files thanks to the program "PLAY_ACC.GTP". 3. Little explanations = =================== 1. The Icons ~~~~~~~~~~~~ The player is displayed into a standard GEM window. Its icons are easy to understand, from left to right : Load : Loads a module into memory. The size of the module ---- must fit into the buffer (see lower). If the program is launched as a PRG, APP or GTP, you can also load a module from the menu. The player can load module packed with Pack Ice any version (Atari packer),Power Packer (Amiga packer) or Noisepakker 1.0 from Delta Force, it will depack it automatically before playing it. (New ! : you can load modules packed with Power Packer or Noisepakker then packed again with pack ice pack ratio for Noisepakker+Ice is more than 70% !!!) Rewind : Rewinds the music (jump to the previous pattern). ------ Play : Start the music ---- Forward: Forwards the music (jump to the next pattern). ------- Pause : Pauses the music. Click an other time on this icon ----- to restart the music. Stop : Stops the music and clear the module from memory. ---- 2. The Frequencies ~~~~~~~~~~~~~~~~~~ There's four buttons under the icons, these buttons allow you to choose the frequencies. Available frequencies are 6.25 KHz, 12.5 KHz, 25 KHz or 50 KHz. Some frequencies aren't available on all machines. On Falcon, 6.25Khz is not available (the DMA soundchip of the Falcon can't restitute sounds at this frequency) and 50Khz isn't available if the CPU speed is 8 Mhz. 50Khz isn't available on STe or MegaSTe. On MegaSTe, 50Khz is available if the CPU speed is 16Mhz and if the cache is on. Note that the more the frequency is high, the more the sound is good but the more the music takes CPU time. It is pretty important to choose the good frequency if you use the player as a desk accessory coz the other running applications will be more or less slowed by the player. (Personnaly, I think that 12.5 is a good value for a STe (even if you can listen at 25), 25 for a MSTe or Falcon030 and 50 for a TT). Watch out: There's a lot of tests which are done : depending the machine and the CPU speed, some frequencies will be unavailable. If you're using a MegaSTe at 16MHz and you're listening at 50KHz, if you switch the CPU time to 8MHz, the frequency will change automatically to 12.5 KHz and 50KHz will be unavailable until CPU speed is 16MHz like the Falcon: if you're listening at 50KHz and if you switch off the 68030 caches, frequency will change automatically. But please, don't play with caches and CPU speed during the player is playing module. Bad things can happen... 3. Loop ~~~~~~~ This button switches the loop flag. If it's ON, the module will play again when it will reach its end, if it's OFF, it will stop and clear from memory. 4. Position display ~~~~~~~~~~~~~~~~~~~ Under these button, there's a graphic display of the current position of the music. 5. The other buttons ~~~~~~~~~~~~~~~~~~~~ Under these 4 buttons (or under the icons if you use a Falcon), there is 3 buttons : -> Quit : Close the player window and stop the music. This ------- music is cleared from memory. If you use the player as PRG, APP or GTP, you can do the same thing with the option QUIT of the menu FILE. -> Play : This button is only available if the program is a ------- desk accessory. Clicking on this button close the player window but the music is still playing on background. Config : This button allows you to configure the player. ------ You can change the size of the allocated memory and the default path for the modules. 1. The size of the buffer - ---------------------- To load the module, the program reserves an amounts of memory when it is launched. By default the size is 256000 bytes. You can increase or decrease this amount, but notice that the new value will be ef- fective only the next time you'll launch the pro- gram coz the memory allocation is done only one time (when the program starts). When you click onto this button, a dialog box appears and displays in the upper part the current size of the reserved memory, type in the lower part the size you want, then click on OK or type return. 2. The default path - ---------------- You can choose the path where the player will search the modules. To choose it, click on the button "Choose path", a fileselector appears to do it. The selected path is displayed into a box. If the path doesn't fit into this box, you can see it by clicking on the arrows buttons to scroll it. To save these parameters, click on OK (Cancel to leave). The new parameters are saved directly into the file of the program, that's why a fileselector appears, choose the player file and click on OK. As this size is saved directly into the program file, you must'nt change the structure of this file, for exemple, you can't pack the player. In fact, you can pack the player but you'll have to unpack it before modifying the size then you'll be able to pack it again. 4. Ultimate Tracker and Multitos = ============================= Ultimate Tracker works fine with Multitos on all machines I've tested (STe, TT and Falcon). It works fine with great screens and graphic card (like Spektrum). The ressource file will use AES features of Multitos on a STe and TT. Be careful : don't modify flags of the program (with the program PRGFLAG.PRG), this program must have its "SUPER" bit set coz it uses a timer under multitos, if you switch off this flag, the system will crash. WARNING ! Never kill the process when the player is playing a module, coz the memory used by the interrupt rout will be free without prevent the player, stop music, then kill the process. 5. The APPL_WRITE commands = ======================= GEM provides a way to communicate beetween applications through an events buffer. This allows an application to take control of an other one. Ultimate Tracker support these commands, so your application can pilot the player. How does it run ? First of all, the player must be resident in memory. The only way to do that is to install it as a desk accessory in monotasking TOS, you can launch it the way you want with Multitos. Then, you must find the AES identification of the player, there's two ways to find this id. The "nicer" method is to use the AES function appl_find like this : id=APPL_FIND(name) where name is the filename of the player without its extension watch out, the name must have 8 characters. This function returns the AES id. If you don't know the current filename of the player, there's an other way to proceed : the player when it is installed, put a cookie into the cookie jar. This cookie is : "UTRK" and the data cookie is the current AES id. Be careful and use this last way of finding AES id if you're sure that you won't able to find it with appl_find. You can imagine easily the problems if there's several instances of the player in memory, you won't able to know who belongs the AES id re- turned by appl_find or by the cookie jar. 1. Commands sent to the player ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Thanks to this AES id, you'll be able to control the player or receive messages from it. You can send commands to the player with the AES function APPL_WRITE. APPL_WRITE needs 3 parame- ters : the identification of the player, the number of bytes to send to the player and the adress of an array of integers (16 bits word)which contain the command to send to the player. These commands have this format : - 1st word : always equal to ID_TRACK (999) - 2nd word : number of the command - 3 - 8 : parameters The commands are : T_LOAD (900) : Load a module into the player buffer. The adress of the path and the name of the module is into the 3rd and the 4th words. (MSB part in 3rd and LSB in 4th). T_PLAY (901) : Plays the module loaded. T_FORWARD (902) : Forwards the module. T_REWIND (903) : Rewinds the module. T_PAUSE (904) : Pauses the module. T_STOP (905) : Stops the module and clears it from memory. T_ABOUT (906) : Display an information box. T_OPEN (907) : Opens the player window. T_CLOSE (908) : Closes the player window. T_FREQ (909) : Changes the frequency. 3rd word contains the frequency (0-3). T_LOOP (910) : Switches the loop flag ON/OFF. T_IDENT (911) : Tells to the player that the application wants receive messages from the player. Word 3 contains AES id of the application. (see next paragraph). T_FIDENT (912) : Tells to the player that the application doesn't want no more messages. (idem). T_INFOS (913) : Ask some informations to the player. See next paragraph for reception of these informations. To see how to use these commands, have a look to the program called \EXEMPLE\SHELL\CMD_TRAX.C. It is a shell which control the player. Note: If you use this feature under Multitos, don't forget to ---- switch on the "GLOBAL" flag of your program, coz when you will send a T_LOAD command to the player, the play- er will read at the address you gave it to get the path of the module, but this address is located into the me- mory of your application. The "GLOBAL" flag allows the player to read into the memory of your application. If this flag is off, Multitos will make a memory pro- tection error and will remove the player from memory. 2. Messages which are received ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can send commands to the player, but you can receive messages from the player too. These messages tell to an ap- plication all things the player does. To receive these messa- ges, you have to proceed this way : - Tell to the player we want messages with the command T_IDENT. Since the player receive this command, it gonna send messages to the application. - Wait for messages in an evnt_multi loop. - When the application needn't no more message, send the com- mand T_FIDENT. Messages have this format : - 1st word : always equel to ID_REPONSE (998) - 2nd word : number of the message - 3 - 8 : parameters Messages are : R_PLAY (951) : The module starts playing. R_FORWARD (952) : Forward. R_REWIND (953) : Rewind. R_PAUSE_ON (954) : Pause is ON. R_PAUSE_OFF(955) : Pause is ON. R_STOP (956) : Module is stopped and cleared from memory. R_OPEN (957) : Player window is opened. R_CLOSE (958) : Player window is closed. R_FREQ (959) : The frequency is changed (new frequency in third word). R_LOOP_OFF (960) : The loop flag is OFF. R_LOOP_ON (961) : The loop flag is ON. R_BEGLOAD (962) : Module is loading. (word 3 contains MSB part of the adress of filename and word 4 contains LSB part.) To access of this filename under MultiTOS, you must be in supervisor mode, coz player has its Super flag ON. R_ENDLOAD (963) : Module has been loaded without error. R_FAILOAD (964) : Error during module loading. R_MOVE (965) : Player window has been moved. New X and Y positions are in word 3 and 4. R_INFOS (966) : This message is sent when the player receives the T_INFOS command. word 3 : player window handle. word 4 : vdi graphic handle. word 5 : AES id. word 6 : Major version number. word 7 : Minor version number. R_POSIT (967) : Current position of the music. word 3 : current position. word 4 : last position. R_QUIT (968) : Player is removed from memory. R_ENDMOD (969) : The module has reached its end (only when loop flag is OFF). R_PROTECMOD(970) : This message is received when the loaded module has corrupted informations, it will be impossible to know where the module gon- ga loop so, it will be impossible to for- ward, rewind or see the player counter. If you need other messages, tell it to me. See the program EXEMPLE\RECEIVE\RECEIVE.C. Note: If you use these feature under MultiTOS, you have to ---- be in Supervisor mode in your application to access the name of the module in the message T_BEGLOAD coz you want to access to an address which is located into the player memory, and this memory area has its flag "Super" set. So this memory can only be accessed in supervisor mode. 6. Limitations = =========== There's some limitations in this program. Up to now, it doesn't test if the file loaded is a module or not, if you try to load anything instead of a module, the program will crash. There's sometimes on Falcon a bug : the player makes some strange noise instead of playing music. It seems that this bug is fixed. Anyway, to avoid this problem, put the program called FPATCH.PRG in your AUTO folder, it fixes 2 bugs (and one of them is the sound initialization, it concern only TOS lesser than 4.05). !!! PLEASE DON'T LAUNCH TWO INSTANCES OF THIS PROGRAM IN THE SAME SESSION. BAD THINGS CAN HAPPEN (Why do you wanna listen two modules in same time ???) 7. Sources and other... = ==================== There three sources given with this program : - SHELL : It's a small shell which can control the player thanks to the appl_write commands. Use it with MintShell under MultiTOS or with a shell into a window under TOS. - RECEIVE : A sample of program which show messages which are sent by the player to an application. Thanks to this sample and the first one, you can see how to make communication in two directions between the player and an application. To see how these programs run, use them simultaneously under MultiTOS with Mintshell (funny !). - PLAY_ACC : A program which allows you to use the player which is a desk accessory as an application for the .MOD files. Install this program in the desktop as an application and then, every time you'll click onto a module icon, the accessory will load and play it. I don't spread the sources of the player now coz there's still bugs to fix and I want to make the memory management again. CPU used ~~~~~~~~ I made some little tests with GEMBENCH to see how CPU time the player takes. I made these tests in 736X560 mode (with 16 co- lors) on Falcon030. 12.5 Khz : 16 % CPU time used 25 Khz : 27 % CPU time used 50 Khz : 50 % CPU time used To contact us : ~~~~~~~~~~~~~ The Black Cats / Equinox Châlet de Riqueval 02420 Bellicourt France 3614 RTEL1/RTEL2 or 3614 TEASER or 3615 STMAG bal Sharpman 8. History = ======= v.1.0ß - Just load and plays modules on Falcon v.1.1ß - Plays modules as a desk accessory (accept Packed modules with Pack Ice) v.1.2ß - New graphix interface. v.1.4ß - Correct lots of bugs. v.1.5ß - Supports Power Packer v.1.6ß - Supports STe/TT replay routines v.1.7ß - works fine under Multitos/supports APPL_WRITE cmds v.1.0 - Supports AES 4.0 on STe or TT v.1.1 - Supports all Pack Ice version and Noisepakker 1.0 v.1.2 - Allows to save default path v.1.3 - Speeded up Falcon replay routine by NOP/DSP CREW (Thanks !) v.1.4 - I fixed a lot of fucking memory bugs v.1.5 - "New" player routine - Allows to change frequency on Falcon030 - Fixes display bugs - Uses 030 cache on TT and memory cache on MSTe v.1.7 - Fix a lot of bugs v.2.0 - Allows communication with a shell in two ways - Use MFP i7 instead of Timer A - Shows current position